循环自动化：/loop 与 /ralph-loop 实战
你会学到什么
前面几节我们用 AI 做需求分析、读源码、做竞品头脑风暴——每一步都是"人提问、AI回答"的单轮交互。但实际开发中有大量需要反复执行的任务：监控部署状态、检查 CI 是否通过、生成超长文档、让 AI 自主迭代直到测试全绿。
本节介绍 Claude Code 中两个核心循环机制：内置的 /loop 定时循环命令和基于 Stop Hook 的 /ralph-loop 自主迭代插件。前者解决"定时巡检"问题，后者解决"AI 自主迭代直到完成"问题。两者配合使用，能让 Claude Code 从"问答工具"升级为"自主工作引擎"。
为什么需要循环自动化
开发中的重复任务
| 任务类型 | 频率 | 传统做法 | 痛点 |
|---|---|---|---|
| 检查 CI/CD 状态 | 每 5-10 分钟 | 手动刷新页面 | 浪费注意力 |
| 监控部署进度 | 部署期间 | 反复执行命令 | 容易忘记 |
| 生成 30+ 页文档 | 项目阶段 | 手动分段复制 | 风格割裂 |
| 让测试全绿 | 重构期间 | 反复跑测试改代码 | 需要全程盯着 |
| 代码质量巡检 | 每日/每周 | 手动触发 linter | 容易遗漏 |
| PR Review 跟进 | 合入前 | 反复看评论 | 响应慢 |
核心需求：AI 不应该只在"你问它"时才工作，它应该能自主、反复执行，直到目标达成。
Claude Code 的三种自主工作模式
| 模式 | 触发条件 | 结束条件 | 适用场景 |
|---|---|---|---|
/loop | 时间间隔到达 | 手动停止 / 7天过期 | 定时轮询、状态检查 |
/ralph-loop | 上一轮完成 | <promise> 标签 / 最大迭代次数 | 超长文档、迭代开发 |
/goal | 上一轮完成 | 条件满足 | 目标驱动的任务（如测试全绿） |
三种模式的本质区别：谁来决定"开始下一轮"？
/loop→ 时钟决定（每隔 N 分钟）/ralph-loop→ 上轮完成即开始（Stop Hook 拦截退出）/goal→ 评估器检查条件（条件不满足就继续）
/loop：定时循环命令
基本用法
/loop 是 Claude Code v2.1.72+ 内置的定时循环命令，三种使用方式：
# 方式一：固定间隔 + 自定义提示词
/loop 5m check if the deployment finished and tell me what happened
# 方式二：动态间隔（Claude 自行决定间隔）
/loop check whether CI passed and address any review comments
# 方式三：裸运行（内置维护提示词）
/loop
bash
| 使用方式 | 间隔 | 提示词 | 场景 |
|---|---|---|---|
/loop 5m check deploy | 固定 5 分钟 | 自定义 | 精确轮询 |
/loop check CI | Claude 动态选择（1分钟-1小时） | 自定义 | 智能巡检 |
/loop | 动态选择 | 内置维护提示词 | 项目维护 |
/loop 15m | 固定 15 分钟 | 内置维护提示词 | 定期维护 |
固定间隔模式
当你提供间隔时间时，Claude 将其转为 cron 表达式并按固定节奏执行：
# 每5分钟检查部署状态
/loop 5m check the deployment status on Vercel, if it succeeds or fails tell me
# 每30分钟检查PR评论
/loop 30m check PR #1234 for new review comments and address them
# 每2小时跑一次代码质量检查
/loop 2h run lint and type check, fix any issues found
bash
间隔支持单位：s（秒）、m（分钟）、h（小时）、d（天）。秒会向上取整到分钟。
动态间隔模式（推荐）
省略间隔时，Claude 根据当前状态动态选择间隔——活动时等短些、安静时等长些：
# Claude 会根据 CI 活跃度自行调整间隔
/loop babysit the release PR - address review comments, fix CI failures
# Claude 会根据部署进度调整检查频率
/loop monitor the staging deploy and report when it's live
bash
动态间隔的优势：
- CI 正在跑 → 等 2-3 分钟
- PR 评论活跃 → 等 3-5 分钟
- 一切安静 → 等 20-30 分钟
- 任务明显完成 → 自动停止循环
内置维护提示词
裸 /loop 运行时，Claude 按优先级顺序执行内置维护任务：
- 继续未完成的工作：上次对话中还没做完的事
- 处理 PR：检查评论、修复 CI 失败、解决合并冲突
- 执行清理：bug hunt、代码简化（没有其他任务时）
# 最简单的用法——让 Claude 自行维护项目
/loop
bash
Claude 不会主动发起新的破坏性操作（如 push、删除），只在已授权的范围内继续工作。
自定义默认提示词：loop.md
你可以用 loop.md 文件替换内置维护提示词：
项目级（优先）：.claude/loop.md
Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.
markdown
用户级（兜底）：~/.claude/loop.md
文件改动在下一轮迭代立即生效，你可以在循环运行时调整指令。
一次性提醒
用自然语言设置一次性提醒：
# 下午3点提醒推代码
remind me at 3pm to push the release branch
# 45分钟后检查集成测试
in 45 minutes, check whether the integration tests passed
# 今天下午5点总结当天工作
remind me at 5pm today to summarize what was accomplished
bash
Claude 会用 cron 表达式精确锁定触发时间，触发后自动删除。
停止和管理
# 停止当前 /loop（等待期间按 Esc）
Esc
# 自然语言管理任务
what scheduled tasks do I have?
cancel the deploy check job
# 底层工具
CronCreate → 创建定时任务
CronList → 列出所有任务
CronDelete → 按ID删除任务
bash
/loop 的重要限制
| 限制 | 说明 |
|---|---|
| 会话作用域 | 关闭终端或新开会话，任务消失 |
| 7天自动过期 | 循环任务最多运行7天 |
| 仅空闲时触发 | Claude 正在忙时，任务排队等待 |
| 最大50个 | 单会话最多50个定时任务 |
| 抖动机制 | 固定间隔任务有最多30分钟随机偏移 |
/ralph-loop：自主迭代循环
什么是 Ralph
Ralph 是一种开发方法论，由 Geoffrey Huntley 提出，核心理念：让 AI 在循环中反复执行同一个 prompt，每次看到上一次的工作成果，自主迭代直到完成。
名字来自《辛普森一家》的角色 Ralph Wiggum——象征"不怕失败、反复尝试"的精神。
官方描述很直白："Ralph is a Bash loop"。
与 /loop 的本质区别
| 维度 | /loop | /ralph-loop |
|---|---|---|
| 触发方式 | 时钟驱动（固定/动态间隔） | 事件驱动（上轮完成即开始） |
| 核心机制 | Cron 定时调度 | Stop Hook 拦截退出 + 重新注入 prompt |
| 上下文 | 每轮独立，不自动继承上轮 | 每轮看到文件系统中的历史修改 |
| 结束条件 | 手动停止 / 7天过期 | <promise> 标签 / --max-iterations |
| 适用场景 | 定时巡检、状态轮询 | 迭代式创建任务（文档生成、功能开发、测试修复） |
| 安装要求 | 内置（v2.1.72+） | 需安装 Ralph Wiggum 插件 |
| 会话外运行 | 不可以 | 不可以（也是会话级） |
一句话区分：/loop 是"闹钟"，按时叫你；/ralph-loop 是"流水线工人"，干完一票接着干下一票。
安装 Ralph Wiggum 插件
Ralph Wiggum 是 Claude Code 的官方插件，通过插件市场安装：
# 在 Claude Code 中安装
/install-plugin ralph-wiggum
# 或手动安装（从 GitHub）
# https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum
bash
安装后获得两个命令：
/ralph-loop— 启动循环/cancel-ralph— 取消循环
基本用法
# 基本格式
/ralph-loop "任务描述" --max-iterations <N> --completion-promise "完成信号"
# 实战示例：生成超长文档
/ralph-loop "根据 outline.md 继续生成产品需求文档的下一章，每章生成独立 .md 文件，完成后输出 <promise>DOC_COMPLETE</promise>" --max-iterations 10
# 实战示例：让测试全绿
/ralph-loop "Run all tests. If any fail, fix them. Output <promise>ALL_GREEN</promise> when every test passes." --max-iterations 20
bash
参数说明：
--max-iterations N：安全上限，防止无限循环（建议始终设置）--completion-promise "TEXT"：Claude 输出此标签时自动停止
工作原理
用户执行 /ralph-loop "prompt"
↓
Claude 开始第一轮工作
↓
Claude 完成任务，准备退出
↓
Stop Hook 拦截退出
↓
Stop Hook 重新注入相同的 prompt
↓
Claude 开始第二轮（看到文件系统中的修改）
↓
...重复...
↓
Claude 输出 <promise>COMPLETE</promise>
↓
Stop Hook 检测到完成信号 → 正常退出
text
关键机制：Stop Hook 在 Claude 试图结束时拦截，检查是否包含 <promise> 完成标签。如果没有，重新注入原始 prompt，让 Claude 继续工作。
Prompt 编写最佳实践
原则一：明确的完成标准
❌ "Build a todo API and make it good."
✅ "Build a REST API for todos.
When complete:
- All CRUD endpoints working
- Input validation in place
- Tests passing (coverage > 80%)
- Output: <promise>COMPLETE</promise>"
markdown
原则二：增量目标
❌ "Create a complete e-commerce platform."
✅ "Phase 1: User authentication (JWT, tests)
Phase 2: Product catalog (list/search, tests)
Phase 3: Shopping cart (add/remove, tests)
Output <promise>COMPLETE</promise> when all phases done."
markdown
原则三：自我纠错指令
❌ "Write code for feature X."
✅ "Implement feature X following TDD:
1. Write failing tests
2. Implement feature
3. Run tests
4. If any fail, debug and fix
5. Refactor if needed
6. Repeat until all green
7. Output: <promise>COMPLETE</promise>"
markdown
原则四：始终设置逃逸阀
# --max-iterations 是安全网
/ralph-loop "Try to implement feature X" --max-iterations 20
# prompt 中也可以说明卡住时怎么办
# "After 15 iterations, if not complete:
# - Document what's blocking progress
# - List what was attempted
# - Suggest alternative approaches"
markdown
实战场景
场景一：监控 CI/CD 部署（/loop）
# 每5分钟检查部署状态，失败了自动排查
/loop 5m check if the Vercel deployment for the main branch succeeded.
If it failed, read the build log, diagnose the issue, and tell me what happened.
# 让 Claude 智能监控 PR
/loop babysit PR #42 - if CI fails, diagnose and push a fix.
If new review comments appear, address them.
bash
场景二：超长文档逐章生成（/ralph-loop）
# 准备大纲后启动循环生成
/ralph-loop "根据 docs/outline.md 继续生成技术方案的下一章。
要求：
1. 每章独立 .md 文件到 docs/ 目录
2. 使用 Mermaid 画图
3. 保持一致的写作风格
4. 完成所有章节后输出 <promise>DOC_COMPLETE</promise>" --max-iterations 15
bash
第一轮生成 01-概述.md，第二轮看到 01 已存在，生成 02-架构设计.md，依此类推。每轮的上下文是文件系统状态，确保风格连贯。
场景三：让测试全绿（/ralph-loop）
# 重构后让 AI 反复修复直到所有测试通过
/ralph-loop "Run the full test suite. If any tests fail:
1. Read the failure message
2. Identify the root cause
3. Make minimal fixes
4. Re-run tests
Output <promise>ALL_TESTS_PASS</promise> when every test passes." --max-iterations 25
bash
场景四：每日项目巡检（/loop + loop.md）
创建 .claude/loop.md：
Check the current branch:
1. Run lint and type check, fix any issues
2. Check if there are uncommitted changes, summarize them
3. Check open PRs for new comments
4. If nothing needs attention, say "All clear" in one line
markdown
# 启动每日巡检，每30分钟一次
/loop 30m
bash
场景五：批量竞品分析（/ralph-loop）
# 配合 local-search 逐个分析竞品
/ralph-loop "查看 docs/competitors-list.md 中的竞品列表，
对下一个未分析的竞品使用 local-search 进行深度调研，
生成竞品分析报告到 docs/competitors/ 目录。
所有竞品分析完成后输出 <promise>ANALYSIS_COMPLETE</promise>" --max-iterations 10
bash
场景六：定时提醒 + 状态检查（一次性提醒）
# 下午3点提醒推代码
remind me at 3pm to push the release branch
# 下班前总结今天的工作
remind me at 5:30pm to summarize today's git commits
# 45分钟后检查构建
in 45 minutes, check whether the Docker build succeeded
bash
场景七：组件库逐个生成（/ralph-loop + Skills）
# 配合 frontend-design Skill 批量生成组件
/ralph-loop "根据 docs/component-list.md 中的组件清单，
使用 /frontend-design 生成下一个未完成的组件，
保存到 src/components/ 目录。
所有组件生成完成后输出 <promise>COMPONENTS_DONE</promise>" --max-iterations 30
bash
/loop 与 /ralph-loop 对比总结
| 维度 | /loop | /ralph-loop |
|---|---|---|
| 驱动方式 | 时间间隔（Cron） | 事件驱动（Stop Hook） |
| 每轮关系 | 独立，不自动继承上下文 | 连续，看到文件系统历史 |
| 结束方式 | 手动停止 / 7天自动过期 | <promise> 标签 / --max-iterations |
| 适用场景 | 轮询状态、定时巡检、提醒 | 迭代创建、文档生成、测试修复 |
| 安装要求 | 内置 | 需安装插件 |
| AI 角色 | 巡逻兵（定期检查） | 流水线工人（持续工作直到完成） |
| token 消耗 | 按次计费，空闲时不消耗 | 持续消耗，直到任务完成 |
| 自定义默认提示 | 支持（loop.md） | 不支持（每次传入 prompt） |
/goal：第三种模式简介
除了 /loop 和 /ralph-loop，Claude Code 还提供了 /goal 命令（v2.1.139+）——设置一个完成条件，Claude 持续工作直到条件满足：
# 设置目标：所有认证测试通过
/goal all tests in test/auth pass and the lint step is clean
# 设置目标：重构完成
/goal every file in src/utils is under 200 lines and all tests pass
# 查看进度
/goal
# 取消
/goal clear
bash
三种模式的完整对比：
| 模式 | 下一轮何时开始 | 何时停止 | 最佳场景 |
|---|---|---|---|
/loop | 时间间隔到达 | 手动 / 7天过期 | 定时巡检、状态监控 |
/ralph-loop | 上轮完成 | <promise> / 最大迭代 | 文档生成、迭代开发 |
/goal | 上轮完成 | 条件满足 | 目标驱动的重构/迁移 |
最佳实践与避坑
选择正确的模式
需要定时执行？→ /loop
需要迭代创建直到完成？→ /ralph-loop
需要达到某个明确条件？→ /goal
只需提醒一次？→ 自然语言提醒
text
/loop 避坑指南
| 坑 | 解决方案 |
|---|---|
| 任务跑完还在循环 | 用动态间隔模式（省略时间），Claude 会在任务完成后自动停止 |
| 关闭终端后任务消失 | 使用 claude --resume 恢复，7天内的任务会恢复 |
| 轮询太频繁浪费 token | 动态间隔比固定间隔更省 token；或用 Monitor 工具替代轮询 |
| 整点触发的抖动 | 避免用 :00 或 :30，用 3 9 * * * 代替 0 9 * * * |
/ralph-loop 避坑指南
| 坑 | 解决方案 |
|---|---|
| 无限循环 | 始终设置 --max-iterations（建议 ≤ 20） |
| 每轮质量下降 | 在 prompt 中加入风格约束，或用 CLAUDE.md 固定风格规则 |
| 风格不一致 | 创建模板文件，在 prompt 中要求遵循模板结构 |
| 某轮生成错误 | 手动编辑文件修正，下一轮 ralph-loop 会看到修改 |
| 卡住不动 | 用 /cancel-ralph 取消，检查 prompt 是否目标不够清晰 |
超长文档的最优策略
| 文档长度 | 推荐方案 |
|---|---|
| 1-10 页 | 直接让 AI 一次性生成 |
| 10-20 页 | /goal 驱动分段生成 |
| 20-50 页 | /ralph-loop 逐章生成 + CLAUDE.md 风格约束 |
| 50+ 页 | /ralph-loop + 模板文件 + 每轮 2000-3000 字 |
与前面章节的联系
| 本章内容 | 关联章节 | 关系 |
|---|---|---|
/loop 内置命令 | 第3章05节 Hooks | /loop 底层使用 CronCreate/CronList/CronDelete 工具 |
/ralph-loop 插件 | 第3章05节 Hooks | ralph-loop 核心机制是 Stop Hook |
| 超长文档生成 | 第7章06节 | 第7章讲了 ralph-loop 的文档场景，本节补充了 /loop 和 /goal |
| 批量竞品分析 | 第8章02节 | 用 ralph-loop 自动化竞品源码分析流程 |
| 项目维护巡检 | 第9章04节 CI/CD | 用 /loop 监控 CI 状态、自动排查构建失败 |
| local-search 配合 | 第5章02节 | ralph-loop 中调用 local-search 做深度搜索 |
本节要点
/loop是"闹钟"：按时触发，适合定时巡检（CI状态、部署监控、PR跟进）/ralph-loop是"流水线工人"：上轮完立即开始下轮，适合迭代创建（文档生成、测试修复、功能开发）/goal是"目标驱动"：设条件，Claude 持续工作直到满足- 动态间隔优于固定间隔：让 Claude 根据状态自行调整检查频率
- 始终设置逃逸阀：
/loop的7天过期、/ralph-loop的--max-iterations、/goal的--goal clear - 三种模式互补：轮询用
/loop、迭代创建用/ralph-loop、条件驱动用/goal
参考资源
- Claude Code 官方文档：Run prompts on a schedule
- Claude Code 官方文档：Goals
- Ralph Wiggum 插件：GitHub - anthropics/claude-code/plugins/ralph-wiggum
- Ralph 原始方法论：ghuntley.com/ralph
↑